perf(frontend): pre-index incoming edges in digital simulation solver - #21

Intent

The ask: "See if this is applicable to us for any of the projects that we have made" and "use claude for it and do it for every repo". This task is that check for the DigiSim repo, using these engineering guidelines that were pasted with the ask:

DATA-ORIENTED DESIGN AND PERFORMANCE ENGINEERING. Prioritize data-oriented design, memory efficiency, cache locality and predictable performance; do not blindly preserve existing data structures; evaluate whether the current representation fits the actual access patterns and workload. Memory layout: prefer contiguous layouts over pointer-heavy structures where appropriate; consider flat arrays instead of hash tables, linked lists and trees; prefer integer indices or handles over raw pointers; consider SoA instead of AoS (and AoSoA) when workloads process single fields across many elements; inline-capacity containers for small collections; bitsets or packed representations for dense flags; bit packing when it really cuts memory or bandwidth. Performance: optimize algorithms and data layouts before adding caches; do not add caches without understanding invalidation, synchronization and memory overhead; do not remove existing caches without showing they are unnecessary or harmful; minimize allocations, copies, indirection and fragmentation; mind cache-line use, memory bandwidth, branch prediction and SIMD; prefer simple predictable access patterns. Critical: do not apply mechanically; preserve correctness, API compatibility and behavior; consider real access patterns; avoid premature optimization and needless complexity; consider concurrency, ownership and lifetimes. Verification: before optimizing identify the critical paths, establish baseline benchmarks, profile CPU, allocations and cache behavior where possible; after optimizing run correctness tests and benchmark against the original (throughput, latency, memory, allocation counts), verify improvements are measurable and repeatable, and reject changes that make performance worse or add unjustified complexity. The goal is the best measurable performance through appropriate data representation; make the common path fast and design data around the most frequent operations.

How it is to be run: (1) First find the real performance-critical paths of this repo. Many projects are dominated by network, model or database waiting; where nothing is CPU or memory bound, say so and stop with a short report and no code change. (2) Where a hot path exists, write a baseline benchmark, profile, and change data layout or algorithm only if the improvement is measured and repeatable. Ship a PR only for changes that beat the baseline with correctness tests green and no API or behavior change, with before-and-after numbers (throughput, latency, memory, allocations) in the PR. Anything that does not clearly win is dropped and listed in the report with the numbers. (3) Deliver a short report: what is hot, what is not, what was changed, measured results, what was rejected and why.

What Changed

• Pre-indexed incoming edges by target node ID and sorted by target handle once per runSimulation call, replacing repeated edge array filtering and sorting on each relaxation iteration with constant-time map lookups.
• Added unit tests in digital.test.ts verifying that component input ordering respects target handles irrespective of edge insertion order and that multi-bit ripple-carry adders converge correctly across forward and reverse node dependency orders.
• Updated agent_docs/simulation-engine.md to document the one-time edge indexing optimization in the digital relaxation loop.

Risk Assessment

✅ Low: The change is a well-bounded, behavior-preserving performance optimization that replaces repeated edge filtering and sorting in the relaxation loop with a one-time per-simulation incoming edge index.

Testing

Stood up DigiSim with its production web build and backend API, driving the real product live through Google Chrome via CDP. Verified real-time digital logic evaluation and carry propagation on a 4-bit ripple-carry adder, tested adversarial out-of-order pin handle routing on the canvas, validated reverse dependency convergence across all simulation test suites (28 tests passed), and measured repeatable 3.0x to 24.6x benchmark speedup with byte-identical output to baseline. Captured 12 visual evidence screenshots and detailed JSON reports in the evidence directory.

• Live validation: ✅ go - 4 of 4 scenarios driven live against the product

Browser screenshot showing DigiSim login page with liquid-glass auth card.

Browser screenshot showing initial DigiSim interactive canvas and schematic workspace.

Browser screenshot showing the Examples Showcase modal with curated 1-click circuits.

Browser screenshot of the 4-Bit Ripple Carry Full Adder loaded onto the live canvas.

Browser screenshot showing real-time circuit evaluation: Sum[0] LED turns ON after toggling Input A0 switch to 1.

Browser screenshot showing carry propagation: after toggling Input B0 to 1, Sum[0] settles to 0 and carry ripples into bit 1.

Browser screenshot showing 2-stage ripple carry propagation lighting CARRY_OUT indicator.

Browser screenshot of Netlist Import dialog validating netlist with reversed handle connections.

Browser screenshot showing adversarial reverse-handle circuit loaded on canvas.

Browser screenshot showing Port A input indicator (top at 31%) active while Port B remains low.

Browser screenshot showing both Port A and Port B indicators active with Result LED active.

Browser screenshot showing Port B indicator (bottom at 69%) active while Port A goes low.

{
  "timestamp": "2026-11-07T02:30:04.131Z",
  "scenario": "Live Interactive Circuit Simulation with Edge-Indexed Relaxation Solver",
  "circuit": "4-Bit Ripple Carry Full Adder from Showcase Gallery",
  "initial_state": {
    "inputs": { "a0": 0, "b0": 0, "a1": 1, "b1": 0 },
    "expected_outputs": { "sum0": 0, "sum1": 1, "cout": 0 },
    "observed_outputs": { "sum0Active": false, "sum1Active": true, "coutActive": false },
    "match": true
  },
  "step1_toggle_a0": {
    "action": "Toggle A0 from 0 to 1",
    "inputs": { "a0": 1, "b0": 0, "a1": 1, "b1": 0 },
    "calculation": "Bit 0: 1+0=1 (Sum0=1, Carry0=0); Bit 1: 1+0+0=1 (Sum1=1, Cout=0)",
    "observed_outputs": { "sum0Active": true, "sum1Active": true, "coutActive": false },
    "match": true
  },
  "step2_toggle_b0": {
    "action": "Toggle B0 from 0 to 1",
    "inputs": { "a0": 1, "b0": 1, "a1": 1, "b1": 0 },
    "calculation": "Bit 0: 1+1=2 (Sum0=0, Carry0=1); Bit 1: 1+0+1=2 (Sum1=0, Cout=1)",
    "observed_outputs": { "sum0Active": false, "sum1Active": false, "coutActive": true },
    "match": true
  },
  "verdict": "PASS"
}

{
  "scenario": "Adversarial Reverse-Edge Handle Ordering on Gate Ports",
  "description": "Wires inserted in reverse order: bottom_in -> handle \"b\" FIRST, top_in -> handle \"a\" SECOND",
  "results": {
    "step1_top_only": {
      "port_a_top_31": true,
      "port_b_btm_69": false,
      "led": true,
      "passed": true
    },
    "step2_both_on": {
      "port_a_top_31": true,
      "port_b_btm_69": true,
      "led": false,
      "passed": true
    },
    "step3_bottom_only": {
      "port_a_top_31": false,
      "port_b_btm_69": true,
      "led": true,
      "passed": true
    }
  },
  "verdict": "PASS"
}

[
  {
    "benchmark": "8-bit ripple adder (66n/89e)",
    "correctness_match": true,
    "baseline": {
      "median_ms": 0.365,
      "min_ms": 0.304,
      "max_ms": 1.427,
      "ops_per_sec": 2506.8
    },
    "optimized": {
      "median_ms": 0.122,
      "min_ms": 0.105,
      "max_ms": 0.708,
      "ops_per_sec": 6725.7
    },
    "speedup": "2.99x"
  },
  {
    "benchmark": "32-bit ripple adder (258n/353e)",
    "correctness_match": true,
    "baseline": {
      "median_ms": 2.195,
      "min_ms": 1.099,
      "max_ms": 4.581,
      "ops_per_sec": 369.8
    },
    "optimized": {
      "median_ms": 0.249,
      "min_ms": 0.242,
      "max_ms": 0.599,
      "ops_per_sec": 3429.2
    },
    "speedup": "8.8x"
  },
  {
    "benchmark": "128-bit ripple adder (1026n/1409e)",
    "correctness_match": true,
    "baseline": {
      "median_ms": 16.254,
      "min_ms": 15.297,
      "max_ms": 20.461,
      "ops_per_sec": 60
    },
    "optimized": {
      "median_ms": 1.439,
      "min_ms": 0.675,
      "max_ms": 2.789,
      "ops_per_sec": 658.8
    },
    "speedup": "11.29x"
  },
  {
    "benchmark": "128-bit ripple adder, reverse order",
    "correctness_match": true,
    "baseline": {
      "median_ms": 120.441,
      "min_ms": 63.805,
      "max_ms": 130.368,
      "ops_per_sec": 9.6
    },
    "optimized": {
      "median_ms": 4.896,
      "min_ms": 2.164,
      "max_ms": 6.631,
      "ops_per_sec": 215.8
    },
    "speedup": "24.6x"
  }
]

Measured before and after

Synthetic ripple-carry adders (about 8 nodes per bit). Median ms per call, jest/jsdom under nice, 3 warm-up runs, at least 15 runs and 1.5 s per case. "rev" lists nodes in reverse dependency order (worst case for relaxation). Baseline is one run; "after" is two independent runs.

Full simulate() output for all 6 benchmark circuits is byte-identical to the baseline. Allocation counts are not reported: heap deltas were too noisy under jest (no --expose-gc); the change removes one array allocation plus one sort per node per relaxation pass.

Not pursued (unmeasured or behavior-risking): event-driven worklist (evaluation order affects latch/feedback results), typed-array value storage, caching parsed customComponents and subcircuit clones. The analog MNA solver, switch-level solver and backend/ML paths were not benchmarked.

Pipeline

Updates from git push no-mistakes